home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / netzwerk / pronet / pronet20.lha / ProNET / autodoc / pronet.doc
Encoding:
Text File  |  1995-06-22  |  6.1 KB  |  190 lines
  1. TABLE OF CONTENTS
  2.  
  3. pronet.device/--Overview--
  4. pronet.device/OpenDevice
  5. pronet.device/CMD_WRITE
  6. pronet.device/ReceivedData
  7. pronet.device/GetConfigString
  8. pronet.device/FreeConfigString
  9.  
  10. pronet.device/--Overview--                         pronet.device/--Overview--
  11.  
  12. This  AutoDoc  is  a  slightly  extended  version  of  V1  to  include  the
  13. differences in ProNET V2.
  14.  
  15. ProNET.device  is able to connect machines for transfering data between
  16. them.   For  the  transfer,  you must select a so-called PORT number, which
  17. must  be  specified  at  device  opening time, and when sending data to the
  18. corresponding port at the other machine, only the application that has this
  19. number will receive the data.  If the destination port doesn't exist on the
  20. other  Amiga,  the  data  will be buffered and will be sent at once when an
  21. application opens this port.
  22.  
  23. What  is  new  in V1, you must supply a Unit number, which corresponds to a
  24. certain hardware interface.
  25.  
  26.   This  device  differs  from  most  other devices in so far as the command
  27. CMD_READ  is  not recognized at all.  Instead, every chunk of data arriving
  28. at  your  port  will be sent to a MessagePort you also specified at opening
  29. time,  no  matter if you want it or not.  This message must be ReplyMsg()ed
  30. after evaluating the data.
  31.  
  32.   The  configuration of the device and applications using it is done by the
  33. file DEVS:ProNET.config.  It is built as follows:
  34.     title data    or
  35.     ; Comment
  36. 'title'  is  a string ending with a colon (':'), and 'data' may be
  37. any string which can be got using the #?ConfigString-Functions.
  38.  
  39. Please  note  that the other side can reset at any time and restart sending
  40. packets.   So  prepare  your  applications  for  it  if  required  --  e.g.
  41. installing a Keyboard ResetHandler or similar notification algorithms.
  42.  
  43. pronet.device/OpenDevice                             pronet.device/OpenDevice
  44.  
  45.     NAME
  46.     OpenDevice -- a request to open a ProNET port
  47.  
  48.     SYNOPSIS
  49.     error = OpenDevice("pronet.device", unit, PNRequest, flags )
  50.     d0            a0               d0    a1         d1
  51.  
  52.     FUNCTION
  53.     Some components of the PNRequest structure must be filled in before
  54.     calling OpenDevice:
  55.  
  56.     pnr_MsgPort        Pointer to a Message Port where incoming
  57.                 data is sent to.
  58.  
  59.     pnr_NetSourcePort    Put your port number here. 0 is reserved
  60.                 for the pronet-handler/-server stuff.
  61.  
  62.     These two values MUST remain until closing the device.
  63.     
  64.     -1  in  pnr_NetSourcePort  has  a special meaning:  The port number
  65.     will  be  taken  from  the ProNET.config file.  pnr_Data1 must then
  66.     point  to  the title string introducing the line.  The first number
  67.     in  the  data  string will then be used as the port number.  If the
  68.     configuration    file   is   incomplete,  the  device  will  return
  69.     PNDERR_BADCONFIG! The title string must include the `:'!
  70.     -1 is also defined as PNP_NAME.
  71.  
  72.     -2  in  pnr_NetSourcePort  also has a  special meaning:  The device
  73.     takes the next free portnumber.
  74.     The new portnumber will then be put in pnr_NetSourcePort.
  75.     -2 is also defined as PNP_NEXTFREE.
  76.  
  77.     INPUTS
  78.     "pronet.device" a pointer to the name of the device to be opened.
  79.             May be another device as well as long as it emulates
  80.             the original !!
  81.     unit         An unsigned long number which will be associated
  82.             with a certain `pronet.config' line.
  83.     PNRequest    a pointer to a PNRequest block
  84.     flags        unused and should be set to 0 !!
  85.  
  86.     RESULTS
  87.     error        0 --> opening OK.
  88.             PNDERR_BADCONFIG - see descr. of pnr_NetSourcePort
  89.             PNDERR_PORTEXISTS - port number is already allocated
  90.             PNDERR_DRIVERTROUBLE - specified driver couldn't open
  91.  
  92. pronet.device/CMD_WRITE                               pronet.device/CMD_WRITE
  93.  
  94.     NAME
  95.     CMD_WRITE -- send data to the other Amiga
  96.     (also PND_WRITE)
  97.  
  98.     FUNCTION
  99.     Sends the data specified in the PNRequest structure as soon as
  100.     possible to other machine.
  101.     The data consists of the second chunk appended to the first one.
  102.     Both chunks added must NOT be longer than $4000 / 16K bytes !!
  103.  
  104.     If the destination port doesn't exist on the remote machine, it
  105.     will be buffered there until the port is opened. The data will
  106.     be then sent in the order it was sent off.
  107.  
  108.     IO REQUEST
  109.     io_Command    CMD_WRITE / PND_WRITE
  110.     pnr_NetDestPort    Destination port number
  111.     pnr_Data1    Pointer to first chunk
  112.     pnr_Length1    Length of first chunk
  113.     pnr_Data2    Pointer to second chunk
  114.     pnr_Length2    Length of second chunk
  115.  
  116.     If you just want to transfer one chunk, set pnr_Length2 to zero.
  117.  
  118.     RESULTS
  119.     io_Error    always zero.
  120.  
  121.     BUGS
  122.     Until now, the machine is freezed while sending. (Bug?)
  123.  
  124.     NOTE
  125.     I-M-P-O-R-T-A-N-T:
  126.     Maximum length is 16K !!
  127.  
  128.     Both lengths are rounded up to word boundaries.
  129.  
  130.     Besides that, the contents of the PNRequest will not be changed !
  131.  
  132.     SEE ALSO
  133.  
  134. pronet.device/ReceivedData                         pronet.device/ReceivedData
  135.  
  136. Received  Data  will  be  sent  to  the Message Port you specified when you
  137. opened 'pronet.device'.  The data part starts behind the Message structure.
  138. It first contains the source port as one word, then the real data. Besides
  139. that, MN_LENGTH contains the length of the data including the source port
  140. word, and the first word of the LN_NAME pointer contains the destination
  141. port number (which shouldn't be of any use at all..)
  142.  
  143. After evaluation of the message, it should be replied.
  144.  
  145. pronet.device/GetConfigString                   pronet.device/GetConfigString
  146.  
  147.    NAME
  148.     GetConfigString -- get string out of DEVS:ProNET.config
  149.  
  150.    SYNOPSIS
  151.     configstr = GetConfigString(titlestring);
  152.     D0                           A0
  153.  
  154.     APTR GetConfigString(char *);
  155.  
  156.    FUNCTION
  157.     Returns the data string corresponding to the title string.
  158.     Must be released by FreeConfigString().
  159.  
  160.    INPUTS
  161.     titlestring    Pointer to null-terminated string. Usually ending
  162.             with a colon (':').
  163.  
  164.    RESULT
  165.     configstr    Pointer to null-terminated string or NULL.
  166.  
  167.    SEE ALSO
  168.     FreeConfigString()
  169.  
  170. pronet.device/FreeConfigString                 pronet.device/FreeConfigString
  171.  
  172.    NAME
  173.     FreeConfigString -- free string got by GetConfigString()
  174.  
  175.    SYNOPSIS
  176.     FreeConfigString(configstring);
  177.               A0
  178.  
  179.     FreeConfigString(char *);
  180.  
  181.    FUNCTION
  182.     Frees memory used by the string got by GetConfigString().
  183.  
  184.    INPUTS
  185.     configstring    Pointer to string got by GetConfigString().
  186.  
  187.    SEE ALSO
  188.     GetConfigString()
  189.  
  190.